Skip to content

docs: rewrite Java template tutorial to AsyncAPI v3#2029

Open
wei123-web wants to merge 7 commits intoasyncapi:masterfrom
wei123-web:docs/update-java-template-v3
Open

docs: rewrite Java template tutorial to AsyncAPI v3#2029
wei123-web wants to merge 7 commits intoasyncapi:masterfrom
wei123-web:docs/update-java-template-v3

Conversation

@wei123-web
Copy link
Copy Markdown

@wei123-web wei123-web commented Mar 25, 2026

Description

Rewrites the "Creating a template – Java" tutorial to use AsyncAPI v3.

Changes made:

  • Updates AsyncAPI document from v2.6.0 to v3.0.0
  • Replaces url: with host: in servers section
  • Migrates TopicFunction to use operations API instead of channels API
  • Renames getTopics to getTopicsFromOperations
  • Updates index.js to use asyncapi.operations().filterByReceive()
  • Updates server URL to use server.host()
  • Fixes duplicated "generated generated" text in output logs

Related issue

Resolves #1828

Summary by CodeRabbit

  • Documentation
    • Updated Java tutorial and examples to AsyncAPI v3 format and refreshed embedded examples.
  • New Features
    • Template now generates topic methods from v3 operations and uses server information for broker URL generation in the generated client.
  • Bug Fixes
    • Fixed duplicated console/log output in the example client and corrected end-of-file newline in the tutorial.

@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Mar 25, 2026

⚠️ No Changeset found

Latest commit: 6222fcc

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 25, 2026

📝 Walkthrough

Walkthrough

Updated the Java template tutorial to AsyncAPI v3 and generator v2: examples, template wiring, and TopicFunction now use AsyncAPI v3 operations and server APIs; example YAML and package.json updated; duplicated log text and EOF newline fixes applied. (≤50 words)

Changes

Cohort / File(s) Summary
Generator Java tutorial
apps/generator/docs/generator-template-java.md
Rewrote examples to AsyncAPI v3 and generator v2: switched from channel-based to operations-based API (TopicFunction({ operations }), getTopicsFromOperations(operations)), updated topic extraction to use op.channel().address() and op.id(), updated template wiring to use asyncapi.operations() and const server = asyncapi.server(params.server), changed generated Client.java broker URL construction to use server.host(), bumped generator.apiVersion / version range in package.json examples, migrated embedded AsyncAPI YAML to asyncapi: 3.0.0, fixed duplicated log text in TestClient.java snippet, removed an unused import, and corrected EOF newline.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change—rewriting the Java template tutorial to use AsyncAPI v3. It follows Conventional Commits format with the 'docs:' prefix and uses imperative mood.
Linked Issues check ✅ Passed The PR successfully addresses all objectives from issue #1828: updates AsyncAPI document from v2.6.0 to v3.0.0, migrates template code to use v3 operations API, and aligns with other language tutorials.
Out of Scope Changes check ✅ Passed All changes are directly related to the stated objectives: AsyncAPI v3 migration, operations API usage, server URL access updates, and duplicate text fix are all in scope.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@asyncapi-bot
Copy link
Copy Markdown
Contributor

asyncapi-bot commented Mar 25, 2026

🚀 Docs preview deployed
Below link points directly to the generator docs preview. May the force be with you!
https://69e981e4f0f57e8cf860f637--asyncapi-website.netlify.app/docs/tools/generator

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
apps/generator/docs/generator-template-java.md (1)

318-318: Wording drift: this should reference operations, not channels.

Since this section migrates to AsyncAPI v3 operations, “regardless of the number of channels” is misleading here.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/generator/docs/generator-template-java.md` at line 318, The sentence
currently references "channels" but this section is about AsyncAPI v3
operations; update the wording around the `TopicFunction` description to
reference "operations" (or "the number of operations in the AsyncAPI v3
document") instead of "channels" so it accurately reflects that the reusable
component applies regardless of operation count in the asyncAPI v3 document.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/generator/docs/generator-template-java.md`:
- Line 393: BROKER_URL is being set to server.host() which yields "host:port"
but the Paho MQTT client requires a URI with a scheme; update the assignment
that sets the static constant BROKER_URL (and the server.host() usage in the
server configuration) to prepend an appropriate scheme such as "tcp://" (e.g.,
"tcp://" + server.host()) so the value becomes a valid URI like
"tcp://test.mosquitto.org:1883" before it is used by the client.
- Around line 355-357: The template is filtering receive operations which misses
AsyncAPI operations with action: send; update getTopicsFromOperations to use
operations.filterBySend() when generating publish/send methods (replace
operations.filterByReceive() with operations.filterBySend()), and apply the same
change to other occurrences where publish methods are derived (the other places
using operations.filterByReceive() for send-method generation) so generated
TestClient sendTemperatureDrop/Rise methods match the document's action: send
operations.

---

Nitpick comments:
In `@apps/generator/docs/generator-template-java.md`:
- Line 318: The sentence currently references "channels" but this section is
about AsyncAPI v3 operations; update the wording around the `TopicFunction`
description to reference "operations" (or "the number of operations in the
AsyncAPI v3 document") instead of "channels" so it accurately reflects that the
reusable component applies regardless of operation count in the asyncAPI v3
document.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 25edfbe6-b065-444b-9743-ce85e40aeb58

📥 Commits

Reviewing files that changed from the base of the PR and between 9e53861 and 10e2010.

📒 Files selected for processing (1)
  • apps/generator/docs/generator-template-java.md

Comment thread apps/generator/docs/generator-template-java.md
Comment thread apps/generator/docs/generator-template-java.md Outdated
@derberg derberg self-assigned this Mar 25, 2026
@Adi-204
Copy link
Copy Markdown
Member

Adi-204 commented Apr 9, 2026

/u

function getTopics(channels) {
const channelsCanSendTo = channels
function getTopicsFromOperations(operations) {
const receiveOperations = operations.filterBySend();
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

operations if you look into line 381 are already filtered correct by receive, so not filter by send again makes no sense, will always be empty, no?

Copy link
Copy Markdown
Member

@derberg derberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please also check Java - package.json file section and make sure generator apversion and compatibility is set correctly

@derberg
Copy link
Copy Markdown
Member

derberg commented Apr 21, 2026

and please make sure that your changes to AsyncAPI YAML are exactly the same as in the similar tutorial but python one

@wei123-web
Copy link
Copy Markdown
Author

Thanks for the review @derberg! Will fix all the issues shortly

@derberg derberg moved this to In Progress in Maintainers work Apr 22, 2026
@sonarqubecloud
Copy link
Copy Markdown

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (1)
apps/generator/docs/generator-template-java.md (1)

356-357: ⚠️ Potential issue | 🔴 Critical

Operation direction is inconsistent, so generated send... methods will be missing.

At Line 356, the tutorial filters with operations.filterBySend(), but at Line 473 and Line 477 both operations are action: receive. This produces no topic methods, while Line 503 and Line 506 call sendTemperatureDrop/Rise, so the tutorial flow breaks.

Suggested fix
 operations:
   temperatureDrop:
-    action: receive
+    action: send
     channel:
       $ref: '#/channels/temperature~1dropped'
   temperatureRise:
-    action: receive
+    action: send
     channel:
       $ref: '#/channels/temperature~1risen'
#!/bin/bash
# Verify direction mismatch between filter and AsyncAPI operation actions in this tutorial file.
set -euo pipefail

FILE="apps/generator/docs/generator-template-java.md"

echo "== filter usage =="
rg -n "filterBySend|filterByReceive" "$FILE"

echo
echo "== operation actions in YAML snippet =="
rg -n "operations:|temperatureDrop:|temperatureRise:|action:" "$FILE" -A3 -B1

echo
echo "Expected: if filterBySend is used for method generation, operations should use action: send."

Based on learnings: “AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x: operations become top-level elements with action property (send/receive) and references to channels.”

Also applies to: 472-479, 503-507

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/generator/docs/generator-template-java.md` around lines 356 - 357, The
tutorial uses operations.filterBySend() but assigns it to receiveOperations, and
the AsyncAPI examples define operations with action: receive, so generated
send... methods are missing; update the usage to match intent by either changing
the filter to operations.filterByReceive() (if you want receive operations) or
updating the sample YAML operations' action values to send (if you intend to
generate send methods), and ensure the variable name receiveOperations and any
subsequent calls to sendTemperatureDrop/Rise or send... methods are consistent
with the chosen filter and operation action.
🧹 Nitpick comments (1)
apps/generator/docs/generator-template-java.md (1)

349-350: Comments/identifier naming drift from behavior; please align wording.

receiveOperations (Line 356) actually stores filterBySend() results, and comments at Line 349-350 / Line 380 still talk about receive operations. This is confusing in a tutorial and easy to copy incorrectly.

Suggested cleanup
- * This function returns a list of objects, one for each receive operation.
+ * This function returns a list of objects, one for each send operation.
...
- const receiveOperations = operations.filterBySend();
+ const sendOperations = operations.filterBySend();
...
- receiveOperations.forEach((op) => {
+ sendOperations.forEach((op) => {

Based on learnings: “Update relevant Generator documentation to accurately reflect PR changes introduced.”

Also applies to: 356-360, 380-380

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/generator/docs/generator-template-java.md` around lines 349 - 350, The
comments in the generator-template-java.md are misleading: the variable
receiveOperations actually stores results from filterBySend(), i.e., send
operations; update all relevant comment text that mentions "receive operations"
(references: receiveOperations, filterBySend()) to correctly say "send
operations" or "filtered send operations" and adjust the descriptive lines (the
block describing name/operationId and any nearby bullets) so they reflect that
the list contains send-operation objects rather than receive-operation objects.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@apps/generator/docs/generator-template-java.md`:
- Around line 356-357: The tutorial uses operations.filterBySend() but assigns
it to receiveOperations, and the AsyncAPI examples define operations with
action: receive, so generated send... methods are missing; update the usage to
match intent by either changing the filter to operations.filterByReceive() (if
you want receive operations) or updating the sample YAML operations' action
values to send (if you intend to generate send methods), and ensure the variable
name receiveOperations and any subsequent calls to sendTemperatureDrop/Rise or
send... methods are consistent with the chosen filter and operation action.

---

Nitpick comments:
In `@apps/generator/docs/generator-template-java.md`:
- Around line 349-350: The comments in the generator-template-java.md are
misleading: the variable receiveOperations actually stores results from
filterBySend(), i.e., send operations; update all relevant comment text that
mentions "receive operations" (references: receiveOperations, filterBySend()) to
correctly say "send operations" or "filtered send operations" and adjust the
descriptive lines (the block describing name/operationId and any nearby bullets)
so they reflect that the list contains send-operation objects rather than
receive-operation objects.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bae6669b-c952-4bf2-8199-e04a021f0b47

📥 Commits

Reviewing files that changed from the base of the PR and between 50f0052 and 6222fcc.

📒 Files selected for processing (1)
  • apps/generator/docs/generator-template-java.md

@wei123-web
Copy link
Copy Markdown
Author

hello @derberg fixed all three issues:
updated apiVersion to v2 and generator range to >=2.0.0 <3.0.0
removed double filterByReceive() in index.js, filtering now happens only inside TopicFunction.js
changed action: send to action: receive in AsyncAPI YAML

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

[📑 Docs]: Rewrite “Creating a template – Java” tutorial to use AsyncAPI v3

4 participants